<HTML><HEAD><TITLE>substring(+String, ?Before, ?Length, ?After, ?SubString)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Strings and Atoms</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>substring(+String, ?Before, ?Length, ?After, ?SubString)</H1>
Succeeds if String2 is a substring of String, with 
    length Length, preceded by Before, and followed by After characters
<DL>
<DT><EM>String</EM></DT>
<DD>String.
</DD>
<DT><EM>Before</EM></DT>
<DD>Integer (from 0 upwards) or variable.
</DD>
<DT><EM>Length</EM></DT>
<DD>Integer (from 0 upwards) or variable.
</DD>
<DT><EM>After</EM></DT>
<DD>Integer (from 0 upwards) or variable.
</DD>
<DT><EM>SubString</EM></DT>
<DD>String or variable.
</DD>
</DL>
<H2>Description</H2>
   Succeeds if String can be split into three substrings,
    StringL, SubString and StringR, such that Before is
    the length of StringL, Length is the length of SubString
    and After is the length of StringR.

<P>
   On backtracking, all such substrings are found.

<P>
   Zero length substrings may be specified.

<P>
   This predicate is very versatile and can be used to
   <UL>
   <LI>check for substrings
   <LI>extract substrings
   <LI>search for substrings
   </UL>

<P>
Note:
   This predicate provides for strings the functionality that the ISO
   sub_atom/5 predicate provides for atoms.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>substring(+, +, +, -, -) is semidet
<LI>substring(+, -, +, +, -) is semidet
<LI>substring(+, +, -, +, -) is semidet
<LI>substring(+, +, -, -, -) is nondet
<LI>substring(+, -, +, -, -) is nondet
<LI>substring(+, -, -, +, -) is nondet
<LI>substring(+, -, -, -, +) is nondet
<LI>substring(+, -, -, -, -) is multi
</UL>
<H3>Fail Conditions</H3>
String cannot be split into substrings of the required lengths, or SubString does not occur within String
<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>String is instantiated, but not to a string.
<DT><EM>(5) type error </EM>
<DD>SubString is neither a string nor a variable.
<DT><EM>(5) type error </EM>
<DD>Any of Before, Length or After are neither integers nor variables.
<DT><EM>(5) type error </EM>
<DD>Any of Before, Length or After negative integers.
<DT><EM>(4) instantiation fault </EM>
<DD>String is not instantiated.
</DL>
<H2>Examples</H2>
<PRE>
Success:
  substring("abracadabra",0,5,_,S2). (gives S2="abrac").
  substring("abracadabra",_,5,0,S2). (gives S2="dabra").
  substring("abracadabra",3,L,3,S2). (gives L=5, S2="acada").
  substring("abracadabra",B,2,A,ab). (gives B=0, A=9; B=7, A=2).
  substring("Banana",3,2,_,S2).      (gives S2="an").

  [eclipse]: substring("ab",B,1,A,S).
  B=0
  A=1
  S="a"     More? (;)
  B=1
  A=0
  S="b"
  yes.

  [eclipse]: substring("charity",B,3,A,S2).
  B=0
  A=4
  S2="cha" More? (;)
  B=1
  A=3
  S2="har" More? (;)
  B=2
  A=2
  S2="ari" More? (;)
  B=3
  A=1
  S2="rit" More? (;)
  B=4
  A=0
  S2="ity"
  yes.

  [eclipse]: substring("abab",B,L,A,S), writeq((B,L,A,S)), nl, fail.
  0, 0, 4, ""           % on backtracking, returns all
  0, 1, 3, "a"          %   substrings of String.
  0, 2, 2, "ab"
  0, 3, 1, "aba"
  0, 4, 0, "abab"
  1, 0, 3, ""
  1, 1, 2, "b"
  1, 2, 1, "ba"
  1, 3, 0, "bab"
  2, 0, 2, ""
  2, 1, 1, "a"
  2, 2, 0, "ab"
  3, 0, 1, ""
  3, 1, 0, "b"
  4, 0, 0, ""
  no (more) solution.

Fail:
  substring("joey",B,L,A,"joy").
  substring("joey",B,2,A"joe").

Error:
  substring(S1,B,L,A,S2).              (Error 4).
  substring(S1,1,2,3,"bc").            (Error 4).
  substring(S1,1,2,3,'str').           (Error 4).
  substring('string',2,3,1,S2).        (Error 5).
  substring("string",2,3,1,'str').     (Error 5).
  substring("string",a,3,1,S2).        (Error 5).
  substring("string",-1,L,A,S2).       (Error 6).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/stratom/substring-3.html">substring / 3</A>, <A HREF="../../kernel/stratom/substring-4.html">substring / 4</A>, <A HREF="../../kernel/stratom/string_length-2.html">string_length / 2</A>, <A HREF="../../kernel/stratom/split_string-4.html">split_string / 4</A>
</BODY></HTML>
